#' @include helpers.R

#' @include Rules-validity.R

#' @include CrmPackClass-class.R

NULL

# NextBest ----

## class ----

#' `NextBest`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' [`NextBest`] is a virtual class for finding next best dose, from which all

#' other specific next best dose classes inherit.

#'

#' @seealso [`NextBestMTD`], [`NextBestNCRM`], [`NextBestDualEndpoint`],

#'   [`NextBestThreePlusThree`], [`NextBestDualEndpoint`], [`NextBestMinDist`],

#'   [`NextBestInfTheory`], [`NextBestTD`], [`NextBestTDsamples`],

#'   [`NextBestMaxGain`], [`NextBestMaxGainSamples`].

#'

#' @aliases NextBest

#' @export

#'

setClass(

  Class = "NextBest",

  contains = "CrmPackClass"

)

# NextBestMTD ----

## class ----

#' `NextBestMTD`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' [`NextBestMTD`] is the class for next best dose based on MTD estimate.

#'

#' @slot target (`proportion`)\cr target toxicity probability, except 0 or 1.

#' @slot derive (`function`)\cr a function which derives the final next best MTD

#'   estimate, based on vector of posterior MTD samples. It must therefore accept

#'   one and only one argument, which is a numeric vector, and return a number.

#'

#' @aliases NextBestMTD

#' @export

#'

.NextBestMTD <- setClass(

  Class = "NextBestMTD",

  slots = c(

    target = "numeric",

    derive = "function"

  ),

  prototype = prototype(

    target = 0.3,

    derive = function(mtd_samples) {

      quantile(mtd_samples, probs = 0.3)

    }

  ),

  contains = "NextBest",

  validity = v_next_best_mtd

)

## constructor ----

#' @rdname NextBestMTD-class

#'

#' @param target (`proportion`)\cr see slot definition.

#' @param derive (`function`)\cr see slot definition.

#'

#' @export

#' @example examples/Rules-class-NextBestMTD.R

#'

NextBestMTD <- function(target, derive) {

  )

}

## default constructor ----

#' @rdname NextBestMTD-class

#' @note Typically, end users will not use the `.DefaultNextBestMTD()` function.

#' @export

.DefaultNextBestMTD <- function() {

    }

  )

}

# NextBestNCRM ----

## class ----

#' `NextBestNCRM`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' [`NextBestNCRM`] is the class for next best dose that finds the next dose

#' with high posterior probability to be in the target toxicity interval.

#'

#' @details To avoid numerical problems, the dose selection algorithm has been

#' implemented as follows: First admissible doses are found, which are those

#' with probability to fall in `overdose` category being below `max_overdose_prob`.

#' Next, within the admissible doses, the maximum probability to fall in the

#' `target` category is calculated. If that is above 5% (i.e. it is not just

#' numerical error), then the corresponding dose is the next recommended dose.

#' Otherwise, the highest admissible dose is the next recommended dose.

#'

#' @slot target (`numeric`)\cr the target toxicity interval (limits included).

#' @slot overdose (`numeric`)\cr the overdose toxicity interval (lower limit

#'   excluded, upper limit included). It is used to filter probability samples.

#' @slot max_overdose_prob (`proportion`)\cr maximum overdose posterior

#'   probability that is allowed, except 0 or 1.

#'

#' @aliases NextBestNCRM

#' @export

#'

.NextBestNCRM <- setClass(

  Class = "NextBestNCRM",

  slots = c(

    target = "numeric",

    overdose = "numeric",

    max_overdose_prob = "numeric"

  ),

  prototype = prototype(

    target = c(0.2, 0.35),

    overdose = c(0.35, 1),

    max_overdose_prob = 0.25

  ),

  contains = "NextBest",

  validity = v_next_best_ncrm

)

## constructor ----

#' @rdname NextBestNCRM-class

#'

#' @param target (`numeric`)\cr see slot definition.

#' @param overdose (`numeric`)\cr see slot definition.

#' @param max_overdose_prob (`proportion`)\cr see slot definition.

#' @export

#' @example examples/Rules-class-NextBestNCRM.R

#'

NextBestNCRM <- function(target,

                         overdose,

                         max_overdose_prob) {

  )

}

## default constructor ----

#' @rdname NextBestNCRM-class

#' @note Typically, end users will not use the `.DefaultNextBestNCRM()` function.

#' @export

.DefaultNextBestNCRM <- function() {

}

# NextBestNCRMLoss ----

## class ----

#' `NextBestNCRMLoss`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' [`NextBestNCRMLoss`] is the class based on NCRM rule and loss function.

#' This class is similar to [`NextBestNCRM`] class, but differences are the

#' addition of loss function and re-defined toxicity intervals, see each

#' toxicity interval documentation and the note for details. As in NCRM rule, first admissible doses are found,

#' which are those with probability to fall in overdose category being below

#' `max_overdose_prob`. Next, within the admissible doses, the loss function is

#' calculated, i.e. `losses` %*% `target`. Finally, the corresponding

#' dose with lowest loss function (Bayes risk) is recommended for the next dose.

#'

#' @slot target (`numeric`)\cr the target toxicity interval (limits included).

#'   It has to be a probability range excluding 0 and 1.

#' @slot overdose (`numeric`)\cr the overdose toxicity interval (lower limit

#'   excluded, upper limit included) or the excessive toxicity interval (lower

#'   limit excluded, upper limit included) if unacceptable is not provided.

#'   It has to be a probability range. It is used to filter probability samples.

#' @slot unacceptable (`numeric`)\cr an unacceptable toxicity

#'   interval (lower limit excluded, upper limit included). This must be

#'   specified if the `overdose` does not include 1. Otherwise, it is `c(1, 1)`

#'   (default), which is essentially a scalar equals 1. It has to be a

#'   probability range.

#' @slot losses (`numeric`)\cr a vector specifying the loss function. If the

#'   `unacceptable` is provided, the vector length must be 4, otherwise 3.

#'

#' @note The loss function should be a vector of either 3 or 4 values.

#'   This is because the loss function values must be specified for each

#'   interval, that is under-dosing, target toxicity, and overdosing toxicity or

#'   under-dosing, target toxicity, overdosing (excessive) toxicity, and

#'   unacceptable toxicity intervals.

#'

#' @aliases NextBestNCRMLoss

#' @export

#'

.NextBestNCRMLoss <- setClass(

  Class = "NextBestNCRMLoss",

  slots = c(

    unacceptable = "numeric",

    losses = "numeric"

  ),

  prototype = prototype(

    unacceptable = c(1, 1),

    losses = c(1, 0, 2)

  ),

  contains = "NextBestNCRM",

  validity = v_next_best_ncrm_loss

)

## constructor ----

#' @rdname NextBestNCRMLoss-class

#'

#' @param target (`numeric`)\cr see slot definition.

#' @param overdose (`numeric`)\cr see slot definition.

#' @param unacceptable (`numeric`)\cr see slot definition.

#' @param max_overdose_prob (`proportion`)\cr see slot definition in [`NextBestNCRM`].

#' @param losses (`numeric`)\cr see slot definition.

#'

#' @export

#' @example examples/Rules-class-NextBestNCRMLoss.R

#'

NextBestNCRMLoss <- function(target,

                             overdose,

                             unacceptable = c(1, 1),

                             max_overdose_prob,

                             losses) {

  )

}

## default constructor ----

#' @rdname NextBestNCRMLoss-class

#' @note Typically, end users will not use the `.DefaultNextBestnCRMLoss()` function.

#' @export

.DefaultNextBestNCRMLoss <- function() {

  )

}

# NextBestThreePlusThree ----

## class ----

#' `NextBestThreePlusThree`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' [`NextBestThreePlusThree`] is the class for next best dose that

#' implements the classical 3+3 dose recommendation. No input is required,

#' hence this class has no slots.

#'

#' @aliases NextBestThreePlusThree

#' @export

#'

.NextBestThreePlusThree <- setClass(

  Class = "NextBestThreePlusThree",

  contains = "NextBest"

)

## constructor ----

#' @rdname NextBestThreePlusThree-class

#'

#' @export

#' @examples

#' # Next best dose class object using the classical 3+3 design.

#' my_next_best <- NextBestThreePlusThree()

NextBestThreePlusThree <- function() {

}

## default constructor ----

#' @rdname NextBestThreePlusThree-class

#' @note Typically, end users will not use the `.DefaultNextBestThreePlusThree()` function.

#' @export

.DefaultNextBestThreePlusThree <- function() {

}

# NextBestDualEndpoint ----

## class ----

#' `NextBestDualEndpoint`

#'

#' @description `r lifecycle::badge("experimental")`

#'

#' [`NextBestDualEndpoint`] is the class for next best dose that is based on the

#' dual endpoint model.

#'

#' @details Under this rule, at first admissible doses are found, which are those

#' with toxicity probability to fall in `overdose` category and being below

#' `max_overdose_prob`. Next, it picks (from the remaining admissible doses) the

#' one that maximizes the probability to be in the `target` biomarker range. By

#' default (`target_relative = TRUE`) the target is specified as relative to the

#' maximum biomarker level across the dose grid or relative to the `Emax`

#' parameter in case a parametric model was selected (i.e. [`DualEndpointBeta`],

#' [`DualEndpointEmax`]). However, if `target_relative = FALSE`, then the

#' absolute biomarker range can be used as a target.

#'

#' @slot target (`numeric`)\cr the biomarker target range that needs to be

#'   reached. For example, the target range \eqn{(0.8, 1.0)} and

#'   `target_relative = TRUE` means that we target a dose with at least

#'   \eqn{80\%} of maximum biomarker level. As an other example,

#'   \eqn{(0.5, 0.8)} would mean that we target a dose between \eqn{50\%} and

#'   \eqn{80\%} of the maximum biomarker level.

#' @slot overdose (`numeric`)\cr the overdose toxicity interval (lower limit

#'   excluded, upper limit included).

#' @slot max_overdose_prob (`proportion`)\cr maximum overdose probability that

#'   is allowed.

#' @slot target_relative (`flag`)\cr is `target` specified as relative? If

#'   `TRUE`, then the `target` is interpreted relative to the maximum, so it

#'   must be a probability range. Otherwise, the `target` is interpreted as

#'   absolute biomarker range.

#' @slot target_thresh (`proportion`)\cr a target probability threshold that

#'   needs to be fulfilled before the target probability will be used for

#'   deriving the next best dose (default to 0.01).

#'

#' @aliases NextBestDualEndpoint

#' @export

#'

.NextBestDualEndpoint <- setClass(

  Class = "NextBestDualEndpoint",

  slots = c(

    target = "numeric",

    overdose = "numeric",

    max_overdose_prob = "numeric",

    target_relative = "logical",

    target_thresh = "numeric"

  ),

  prototype = prototype(

    target = c(0.9, 1),

    overdose = c(0.35, 1),

    max_overdose_prob = 0.25,

    target_relative = TRUE,

    target_thresh = 0.01

  ),

  contains = "NextBest",

  validity = v_next_best_dual_endpoint

)

## constructor ----

#' @rdname NextBestDualEndpoint-class

#'

#' @param target (`numeric`)\cr see slot definition.

#' @param overdose (`numeric`)\cr see slot definition.

#' @param max_overdose_prob (`proportion`)\cr see slot definition.

#' @param target_relative (`flag`)\cr see slot definition.

#' @param target_thresh (`proportion`)\cr see slot definition.

#'

#' @export

#' @example examples/Rules-class-NextBestDualEndpoint.R

#'

NextBestDualEndpoint <- function(target,

                                 overdose,

                                 max_overdose_prob,

                                 target_relative = TRUE,

                                 target_thresh = 0.01) {

  )

}

## default constructor ----

#' @rdname NextBestDualEndpoint-class

#' @note Typically, end users will not use the `.DefaultNextBestDualEndpoint()` function.

#' @export

.DefaultNextBestDualEndpoint <- function() {

  )

}

# NextBestMinDist ----

## class ----

#' `NextBestMinDist`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' [`NextBestMinDist`] is the class for next best dose that is based on minimum

#' distance to target probability.

#'

#' @slot target (`proportion`)\cr single target toxicity probability, except

#'   0 or 1.

#'

#' @aliases NextBestMinDist

#' @export

#'

.NextBestMinDist <- setClass(

  Class = "NextBestMinDist",

  slots = c(

    target = "numeric"

  ),

  prototype = prototype(

    target = 0.3

  ),

  contains = "NextBest",

  validity = v_next_best_min_dist

)

## constructor ----

#' @rdname NextBestMinDist-class

#'

#' @param target (`proportion`)\cr see slot definition.

#'

#' @export

#' @example examples/Rules-class-NextBestMinDist.R

#'

NextBestMinDist <- function(target) {

}

## default constructor ----

#' @rdname NextBestMinDist-class

#' @note Typically, end users will not use the `.DefaultNextBestMinDist()` function.

#' @export

.DefaultNextBestMinDist <- function() {

}

# NextBestInfTheory ----

## class ----

#' `NextBestInfTheory`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' [`NextBestInfTheory`] is the class for next best dose that is based on

#' information theory as proposed in https://doi.org/10.1002/sim.8450.

#'

#' @slot target (`proportion`)\cr target toxicity probability, except 0 or 1.

#' @slot asymmetry (`number`)\cr value of the asymmetry exponent in the

#'   divergence function that describes the rate of penalization for overly

#'   toxic does. It must be a value from \eqn{(0, 2)} interval.

#'

#' @aliases NextBestInfTheory

#' @export

#'

.NextBestInfTheory <- setClass(

  Class = "NextBestInfTheory",

  slots = c(

    target = "numeric",

    asymmetry = "numeric"

  ),

  prototype = prototype(

    target = 0.3,

    asymmetry = 1

  ),

  contains = "NextBest",

  validity = v_next_best_inf_theory

)

## constructor ----

#' @rdname NextBestInfTheory-class

#'

#' @param target (`proportion`)\cr see slot definition.

#' @param asymmetry (`number`)\cr see slot definition.

#'

#' @export

#'

NextBestInfTheory <- function(target, asymmetry) {

}

## default constructor ----

#' @rdname NextBestInfTheory-class

#' @note Typically, end users will not use the `.DefaultNextBestInfTheory()` function.

#' @export

.DefaultNextBestInfTheory <- function() {

}

# NextBestTD ----

## class ----

#' `NextBestTD`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' [`NextBestTD`] is the class to find a next best dose based on pseudo

#' DLT model without samples. Namely, it is to find two next best doses, one

#' for allocation during the trial and the second for final recommendation at

#' the end of a trial without involving any samples, i.e. only DLT responses

#' will be incorporated for the dose-allocation. This is based solely on the

#' probabilities of the occurrence of a DLT obtained by using the modal estimates

#' of the model parameters. There are two target probabilities of the

#' occurrence of a DLT that must be specified: target probability to be used

#' during the trial and target probability to be used at the end of the trial.

#' It is suitable to use it only with the [`ModelTox`] model class.

#'

#' @slot prob_target_drt (`proportion`)\cr the target probability (except 0 or 1)

#'   of the occurrence of a DLT to be used during the trial.

#' @slot prob_target_eot (`proportion`)\cr the target probability (except 0 or 1)

#'   of the occurrence of a DLT to be used at the end of the trial.

#'

#' @aliases NextBestTD

#' @export

#'

.NextBestTD <- setClass(

  Class = "NextBestTD",

  slots = c(

    prob_target_drt = "numeric",

    prob_target_eot = "numeric"

  ),

  prototype = prototype(

    prob_target_drt = 0.35,

    prob_target_eot = 0.3

  ),

  contains = "NextBest",

  validity = v_next_best_td

)

## default constructor ----

#' @rdname NextBestTD-class

#' @note Typically, end users will not use the `.DefaultNextBestTD()` function.

#' @export

.DefaultNextBestTD <- function() {

}

## constructor ----

#' @rdname NextBestTD-class

#'

#' @param prob_target_drt (`proportion`)\cr see slot definition.

#' @param prob_target_eot (`proportion`)\cr see slot definition.

#'

#' @export

#' @examples

#' my_next_best <- NextBestTD(0.35, 0.3)

NextBestTD <- function(prob_target_drt, prob_target_eot) {

  )

}

# NextBestTDsamples ----

## class ----

#' `NextBestTDsamples`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' [`NextBestTDsamples`] is the class to find a next best dose based on Pseudo

#' DLT model with samples. Namely, it is to find two next best doses, one

#' for allocation during the trial and the second for final recommendation at

#' the end of a trial. Hence, there are two target probabilities of the

#' occurrence of a DLT that must be specified: target probability to be used

#' during the trial and target probability to be used at the end of the trial.

#'

#' @slot derive (`function`)\cr derives, based on a vector of posterior dose

#'   samples, the target dose that has the probability of the occurrence of

#'   DLT equals to either the `prob_target_drt` or `prob_target_eot`. It must

#'   therefore accept one and only one argument, which is a numeric vector, and

#'   return a number.

#'

#' @aliases NextBestTDsamples

#' @export

#'

.NextBestTDsamples <- setClass(

  Class = "NextBestTDsamples",

  slots = c(

    derive = "function"

  ),

  prototype = prototype(

    derive = function(dose_samples) {

      quantile(dose_samples, prob = 0.3)

    }

  ),

  contains = "NextBestTD",

  validity = v_next_best_td_samples

)

## constructor ----

#' @rdname NextBestTDsamples-class

#'

#' @param prob_target_drt (`proportion`)\cr see slot definition in [`NextBestTD`].

#' @param prob_target_eot (`proportion`)\cr see slot definition in [`NextBestTD`].

#' @param derive (`function`)\cr see slot definition.

#'

#' @export

#' @example examples/Rules-class-NextBestTDsamples.R

#'

NextBestTDsamples <- function(prob_target_drt, prob_target_eot, derive) {

  )

}

## default constructor ----

#' @rdname NextBestTDsamples-class

#' @note Typically, end users will not use the `.DefaultNextBestTDsamples()` function.

#' @export

.DefaultNextBestTDsamples <- function() {

    }

  )

}

# NextBestMaxGain ----

## class ----

#' `NextBestMaxGain`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' [`NextBestMaxGain`] is the class to find a next best dose with maximum gain

#' value based on a pseudo DLT and efficacy models without samples. It is based

#' solely on the probabilities of the occurrence of a DLT and the values

#' of the mean efficacy responses obtained by using the modal estimates of the

#' DLT and efficacy model parameters. There are two target probabilities of the

#' occurrence of a DLT that must be specified: target probability to be used

#' during the trial and target probability to be used at the end of the trial.

#' It is suitable to use it only with the [`ModelTox`] model and [`ModelEff`]

#' classes (except [`EffFlexi`]).

#'

#' @slot prob_target_drt (`proportion`)\cr the target probability of the

#'   occurrence of a DLT to be used during the trial.

#' @slot prob_target_eot (`proportion`)\cr the target probability of the

#'   occurrence of a DLT to be used at the end of the trial.

#'

#' @aliases NextBestMaxGain

#' @export

#'

.NextBestMaxGain <- setClass(

  Class = "NextBestMaxGain",

  slots = c(

    prob_target_drt = "numeric",

    prob_target_eot = "numeric"

  ),

  prototype = prototype(

    prob_target_drt = 0.35,

    prob_target_eot = 0.3

  ),

  contains = "NextBest",

  validity = v_next_best_td

)

## constructor ----

#' @rdname NextBestMaxGain-class

#'

#' @param prob_target_drt (`proportion`)\cr see slot definition.

#' @param prob_target_eot (`proportion`)\cr see slot definition.

#'

#' @export

#' @examples

#' my_next_best <- NextBestMaxGain(0.35, 0.3)

NextBestMaxGain <- function(prob_target_drt, prob_target_eot) {

  )

}

## default constructor ----

#' @rdname NextBestMaxGain-class

#' @note Typically, end users will not use the `.DefaultNextBestMaxGain()` function.

#' @export

.DefaultNextBestMaxGain <- function() {

}

# NextBestMaxGainSamples ----

## class ----

#' `NextBestMaxGainSamples`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' [`NextBestMaxGainSamples`] is the class to find a next best dose with maximum

#' gain value based on a pseudo DLT and efficacy models and DLT and efficacy

#' samples. There are two target probabilities of the occurrence of a DLT that

#' must be specified: target probability to be used during the trial and target

#' probability to be used at the end of the trial.

#' It is suitable to use it only with the [`ModelTox`] model and [`ModelEff`]

#' classes.

#'

#' @slot derive (`function`)\cr derives, based on a vector of posterior dose

#'   samples, the target dose that has the probability of the occurrence of

#'   DLT equals to either the `prob_target_drt` or `prob_target_eot`. It must

#'   therefore accept one and only one argument, which is a numeric vector, and

#'   return a number.

#' @slot mg_derive (`function`)\cr derives, based on a vector of posterior dose

#'   samples that give the maximum gain value, the final next best estimate of

#'   the dose that gives the maximum gain value. It must therefore accept one

#'   and only one argument, which is a numeric vector, and return a number.

#'

#' @aliases NextBestMaxGainSamples

#' @export

#'

.NextBestMaxGainSamples <- setClass(

  Class = "NextBestMaxGainSamples",

  slots = c(

    derive = "function",

    mg_derive = "function"

  ),

  prototype = prototype(

    prob_target_drt = 0.35,

    prob_target_eot = 0.3,

    derive = function(dose_samples) {

      as.numeric(quantile(dose_samples, prob = 0.3))

    },

    mg_derive = function(dose_samples) {

      as.numeric(quantile(dose_samples, prob = 0.5))

    }

  ),

  contains = "NextBestMaxGain",

  validity = v_next_best_max_gain_samples

)

## constructor ----

#' @rdname NextBestMaxGainSamples-class

#'

#' @param prob_target_drt (`proportion`)\cr see slot definition in [`NextBestMaxGain`].

#' @param prob_target_eot (`proportion`)\cr see slot definition in [`NextBestMaxGain`].

#' @param derive (`function`)\cr see slot definition.

#' @param mg_derive (`function`)\cr see slot definition.

#'

#' @export

#' @example examples/Rules-class-NextBestMaxGainSamples.R

#'

NextBestMaxGainSamples <- function(prob_target_drt,

                                   prob_target_eot,

                                   derive,

                                   mg_derive) {

  )

}

## default constructor ----

#' @rdname NextBestMaxGainSamples-class

#' @note Typically, end users will not use the `.DefaultNextBestMaxGainSamples()` function.

#' @export

.DefaultNextBestMaxGainSamples <- function() {

    },

    }

  )

}

# NextBestProbMTDLTE ----

## class ----

#' `NextBestProbMTDLTE`

#'

#' @description `r lifecycle::badge("experimental")`

#'

#' [`NextBestProbMTDLTE`] is the class of finding a next best dose that selects

#' the dose with the highest probability of having a toxicity rate less or equal

#' to the toxicity target.

#' The dose is determined by calculating the posterior toxicity probability

#' for each dose per iteration and select the maximum dose that has a toxicity

#' probability below or equal to the target. The dose with the highest frequency

#' of being selected as MTD across iterations is the next best dose. Placebo

#' is not considered in the calculation and removed from the dose grid for

#' any calculations.

#'

#' @slot target (`numeric`)\cr the target toxicity probability.

#'

#' @aliases NextBestProbMTDLTE

#' @export

#'

.NextBestProbMTDLTE <- setClass(

  Class = "NextBestProbMTDLTE",

  slots = c(target = "numeric"),

  prototype = prototype(target = 0.3),

  contains = "NextBest",

  validity = v_next_best_prob_mtd_lte

)

## constructor ----

#' @rdname NextBestProbMTDLTE-class

#'

#' @param target (`numeric`)\cr see slot definition.

#' @export

#' @example examples/Rules-class-NextBestProbMTDLTE.R

#'

NextBestProbMTDLTE <- function(target) {

}

## default constructor ----

#' @rdname NextBestProbMTDLTE-class

#' @note Typically, end users will not use the `.DefaultNextBestProbMTDLTE()` function.

#' @export

.DefaultNextBestProbMTDLTE <- function() {

}

# NextBestProbMTDMinDist ----

## class ----

#' `NextBestProbMTDMinDist`

#'

#' @description `r lifecycle::badge("experimental")`

#'

#' [`NextBestProbMTDMinDist`] is the class of finding a next best dose that selects

#' the dose with the highest probability of having a toxicity rate with the

#' smallest distance to the toxicity target.

#' The dose is determined by calculating the posterior toxicity probability

#' for each dose per iteration and select the dose that has the smallest toxicity

#' probability distance to the target. The dose with the highest frequency

#' of being selected as MTD across iterations is the next best dose. Placebo

#' is not considered as the next dose and for that reason not used in

#' calculations. I.e. for placebo the toxicity probability distance to target

#' is not calculated and taken into account for determination of the next dose.

#'

#' @slot target (`numeric`)\cr the target toxicity probability.

#'

#' @aliases NextBestProbMTDMinDist

#' @export

#'

.NextBestProbMTDMinDist <- setClass(

  Class = "NextBestProbMTDMinDist",

  slots = c(target = "numeric"),

  prototype = prototype(target = 0.3),

  contains = "NextBest",

  validity = v_next_best_prob_mtd_min_dist

)

## constructor ----

#' @rdname NextBestProbMTDMinDist-class

#'

#' @param target (`numeric`)\cr see slot definition.

#' @export

#' @example examples/Rules-class-NextBestProbMTDMinDist.R

#'

NextBestProbMTDMinDist <- function(target) {

}

## default constructor ----

#' @rdname NextBestProbMTDMinDist-class

#' @note Typically, end users will not use the `.DefaultNextBestProbMTDMinDist()` function.

#' @export

.DefaultNextBestProbMTDMinDist <- function() {

}

# Increments ----

## class ----

#' `Increments`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' [`Increments`] is a virtual class for controlling increments, from which all

#' other specific increments classes inherit.

#'

#' @seealso [`IncrementsRelative`], [`IncrementsRelativeDLT`],

#'   [`IncrementsDoseLevels`], [`IncrementsHSRBeta`], [`IncrementsMin`].

#'

#' @aliases Increments

#' @export

#'

setClass(

  Class = "Increments",

  contains = "CrmPackClass"

)

# IncrementsRelative ----

## class ----

#' `IncrementsRelative`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' [`IncrementsRelative`] is the class for increments control based on relative

#' differences in intervals.

#'

#' @slot intervals (`numeric`)\cr a vector with the left bounds of the relevant

#'   intervals. For example, `intervals  = c(0, 50, 100)` specifies three intervals:

#'   \eqn{(0, 50)}, \eqn{[50, 100)} and \eqn{[100, +Inf)}. That means, the right

#'   bound of the intervals are exclusive to the interval and the last interval

#'   goes from the last value to infinity.

#' @slot increments (`numeric`)\cr a vector of the same length with the maximum

#'   allowable relative increments in the `intervals`.

#'

#' @aliases IncrementsRelative

#' @export

#'

.IncrementsRelative <- setClass(

  Class = "IncrementsRelative",

  slots = c(

    intervals = "numeric",

    increments = "numeric"

  ),

  prototype = prototype(

    intervals = c(0, 2),

    increments = c(2, 1)

  ),

  contains = "Increments",

  validity = v_increments_relative

)

## constructor ----

#' @rdname IncrementsRelative-class

#'

#' @param intervals (`numeric`)\cr see slot definition.

#' @param increments (`numeric`)\cr see slot definition.

#'

#' @export

#' @example examples/Rules-class-IncrementsRelative.R

#'

IncrementsRelative <- function(intervals, increments) {

  )

}

## default constructor ----

#' @rdname IncrementsRelative-class

#' @note Typically, end users will not use the `.DefaultIncrementsRelative()` function.

#' @export

.DefaultIncrementsRelative <- function() {

}

# IncrementsRelativeDLT ----

## class ----

#' `IncrementsRelativeDLT`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' [`IncrementsRelativeDLT`] is the class for increments control based on

#' relative differences in terms of DLTs.

#'

#' @slot intervals (`integer`)\cr a vector with the left bounds of the

#'   relevant DLT intervals. For example, `intervals  = c(0, 1, 3)` specifies

#'   three intervals (sets of DLTs: first, 0 DLT; second 1 or 2 DLTs; and the third

#'   one, at least 3 DLTs. That means, the right bound of the intervals are

#'   exclusive to the interval and the last interval goes from the last value to

#'   infinity.

#' @slot increments (`numeric`)\cr a vector of maximum allowable relative

#'   increments corresponding to `intervals`. IT must be of the same length

#'   as the length of `intervals`.

#'

#' @note This considers all DLTs across all cohorts observed so far.

#'

#' @seealso [IncrementsRelativeDLTCurrent] which only considers the DLTs

#'   in the current cohort.

#'

#' @aliases IncrementsRelativeDLT

#' @export

#'

.IncrementsRelativeDLT <- setClass(

  Class = "IncrementsRelativeDLT",

  slots = representation(

    intervals = "integer",

    increments = "numeric"

  ),

  prototype = prototype(

    intervals = c(0L, 1L),

    increments = c(2, 1)

  ),

  contains = "Increments",

  validity = v_increments_relative_dlt

)

## constructor ----

#' @rdname IncrementsRelativeDLT-class

#'

#' @param intervals (`numeric`)\cr see slot definition.

#' @param increments (`numeric`)\cr see slot definition.

#'

#' @export

#' @example examples/Rules-class-IncrementsRelativeDLT.R

#'

IncrementsRelativeDLT <- function(intervals, increments) {

  )

}

## default constructor ----

#' @rdname IncrementsRelativeDLT-class

#' @note Typically, end users will not use the `.DefaultIncrementsRelativeDLT()` function.

#' @export

.DefaultIncrementsRelativeDLT <- function() {

}

# IncrementsRelativeDLTCurrent ----

## class ----

#' `IncrementsRelativeDLTCurrent`

#'

#' @description `r lifecycle::badge("experimental")`

#'

#' [`IncrementsRelativeDLTCurrent`] is the class for increments control based on

#' relative differences and current DLTs. The class is based on the number of

#' DLTs observed in the current cohort, but not cumulatively over all cohorts

#' so far.

#'

#' @seealso [IncrementsRelativeDLT].

#'

#' @aliases IncrementsRelativeDLTCurrent

#' @export

#'

.IncrementsRelativeDLTCurrent <- setClass(

  Class = "IncrementsRelativeDLTCurrent",

  contains = "IncrementsRelativeDLT"

)

## constructor ----

#' @rdname IncrementsRelativeDLTCurrent-class

#'

#' @inheritParams IncrementsRelativeDLT

#'

#' @export

#' @example examples/Rules-class-IncrementsRelativeDLTCurrent.R

#'

IncrementsRelativeDLTCurrent <- function(intervals = c(0, 1),

                                         increments = c(2, 1)) {

  )

}

## default constructor ----

#' @rdname IncrementsRelativeDLTCurrent-class

#' @note Typically, end users will not use the `.DefaultIncrementsRelativeDLTCurrent()` function.

#' @export

.DefaultIncrementsRelativeDLTCurrent <- function() { # nolint

}

# IncrementsRelativeParts ----

## class ----

#' `IncrementsRelativeParts`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' [`IncrementsRelativeParts`] is the class for increments control based on

#' relative differences in intervals, with special rules for part 1 and

#' beginning of part 2.

#'

#' @details This class works only in conjunction with [`DataParts`] objects. If

#' part 2 will just be started in the next cohort, then the next maximum dose

#' will be either `dlt_start` (e.g. -1) shift of the last part 1 dose in case

#' of a DLT in part 1, or `clean_start` shift (e.g. -1) in case of no DLTs in

#' part 1, given that `clean_start <= 0` (see description of `clean_start`

#' slot for more details). If part 1 will still be on in the next cohort,

#' then the next dose level will be the next higher dose level in the

#' `part1Ladder` slot of the data object. If part 2 has been started before,

#' the usual relative increment rules apply, see [`IncrementsRelative`].

#'

#' @slot dlt_start (`integer`)\cr a scalar, the dose level increment for starting

#'   part 2 in case of at least one DLT event in part 1.

#' @slot clean_start (`integer`)\cr a scalar, the dose level increment for

#'   starting part 2 in case of no DLTs in part 1. If `clean_start <= 0`,

#'   then the part 1 ladder will be used to find the maximum next dose.

#'   Otherwise, the relative increment rules will be applied to find the next

#'   maximum dose level.

#'

#' @note We require that `clean_start >= dlt_start`. However, this precondition

#'   is not a prerequisite for any function (except of the class' validation

#'   function) that works with objects of this class. It is rather motivated by

#'   the semantics. That is, if we observe a DLT in part 1, we cannot be more

#'   aggressive than in case of a clean part 1 without DLT.

#'

#' @aliases IncrementsRelativeParts

#' @export

#'

.IncrementsRelativeParts <- setClass(

  Class = "IncrementsRelativeParts",

  slots = representation(

    dlt_start = "integer",

    clean_start = "integer"

  ),

  prototype = prototype(

    dlt_start = -1L,

    clean_start = 1L

  ),

  contains = "IncrementsRelative",

  validity = v_increments_relative_parts

)

## constructor ----

#' @rdname IncrementsRelativeParts-class

#'

#' @param dlt_start (`count`)\cr see slot definition.

#' @param clean_start (`count`)\cr see slot definition.

#' @inheritDotParams IncrementsRelative

#'

#' @export

#' @example examples/Rules-class-IncrementsRelative-DataParts.R

#'

IncrementsRelativeParts <- function(dlt_start, clean_start, ...) {

    ...

  )

}

## default constructor ----

#' @rdname IncrementsRelativeParts-class

#' @note Typically, end users will not use the `.DefaultIncrementsRelativeParts()` function.

#' @export

.DefaultIncrementsRelativeParts <- function() {

}

# IncrementsDoseLevels ----

## class ----

#' `IncrementsDoseLevels`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' [`IncrementsDoseLevels`] is the class for increments control based on the

#' number of dose levels.

#'

#' @slot levels (`count`)\cr maximum number of dose levels to increment for

#'   the next dose. It defaults to 1, which means that no dose skipping is

#'   allowed, i.e. the next dose can be maximum one level higher than the current

#'   base dose. The current base dose level is the dose level used to increment

#'   from (see `basis_level` parameter).

#' @slot basis_level (`string`)\cr defines the current base dose level. It can

#'   take one out of two possible values: `last` or `max`.

#'   If `last` is specified (default), the current base dose level is set to the

#'   last dose given. If `max` is specified, then the current base dose level is

#'   set to the maximum dose level given.

#'

#' @aliases IncrementsDoseLevels

#' @export

#'

.IncrementsDoseLevels <- setClass(

  Class = "IncrementsDoseLevels",

  slots = representation(

    levels = "integer",

    basis_level = "character"

  ),

  prototype = prototype(

    levels = 1L,

    basis_level = "last"

  ),

  contains = "Increments",

  validity = v_increments_dose_levels

)

## constructor ----

#' @rdname IncrementsDoseLevels-class

#'

#' @param levels (`count`)\cr see slot definition.

#' @param basis_level (`string`)\cr see slot definition.

#'

#' @export

#' @example examples/Rules-class-IncrementsDoseLevels.R

#'

IncrementsDoseLevels <- function(levels = 1L, basis_level = "last") {

  )

}

## default constructor ----

#' @rdname IncrementsDoseLevels-class

#' @note Typically, end users will not use the `.DefaultIncrementsDoseLevels()` function.

#' @export

.DefaultIncrementsDoseLevels <- function() {

}

# IncrementsHSRBeta ----

## class ----

#' `IncrementsHSRBeta`

#'

#' @description `r lifecycle::badge("experimental")`

#'

#' [`IncrementsHSRBeta`] is a class for limiting further increments using

#' a Hard Safety Rule based on the Bin-Beta model.

#' Increment control is based on the number of observed DLTs and number of

#' subjects at each dose level. The probability of toxicity is calculated

#' using a Bin-Beta model with prior (a,b). If the probability exceeds

#' the threshold for a given dose, that dose and all doses above are excluded

#' from further escalation.

#' This is a hard safety rule that limits further escalation based on the

#' observed data per dose level, independent from the underlying model.

#'

#' @slot target (`proportion`)\cr the target toxicity, except

#'   0 or 1.

#' @slot prob (`proportion`)\cr the threshold probability (except 0 or 1) for

#'   a dose being toxic.

#' @slot a (`number`)\cr shape parameter \eqn{a > 0} of probability distribution

#'   Beta (a,b).

#' @slot b (`number`)\cr shape parameter \eqn{b > 0} of probability distribution

#'   Beta (a,b).

#'

#' @aliases IncrementsHSRBeta

#' @export

#'

.IncrementsHSRBeta <- setClass(

  Class = "IncrementsHSRBeta",

  slots = c(

    target = "numeric",

    prob = "numeric",

    a = "numeric",

    b = "numeric"

  ),

  prototype = prototype(

    target = 0.3,

    prob = 0.95,

    a = 1,

    b = 1

  ),

  contains = "Increments",

  validity = v_increments_hsr_beta

)

## constructor ----

#' @rdname IncrementsHSRBeta-class

#'

#' @param target (`proportion`)\cr see slot definition.

#' @param prob (`proportion`)\cr see slot definition.

#' @param a (`number`)\cr see slot definition.

#' @param b (`number`)\cr see slot definition.

#'

#' @example examples/Rules-class-IncrementsHSRBeta.R

#' @export

#'

IncrementsHSRBeta <- function(target = 0.3,

                              prob = 0.95,

                              a = 1,

                              b = 1) {

  )

}

## default constructor ----

#' @rdname IncrementsHSRBeta-class

#' @note Typically, end users will not use the `.DefaultIncrementsHSRBeta()` function.

#' @export

.DefaultIncrementsHSRBeta <- function() {

}

# IncrementsMin ----

## class ----

#' `IncrementsMin`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' [`IncrementsMin`] is the class that combines multiple increment rules with

#' the `minimum` operation. Slot `increments_list` contains all increment rules,

#' which are itself the objects of class [`Increments`]. The minimum of these

#' individual increments is taken to give the final maximum increment.

#'

#' @slot increments_list (`list`)\cr list with increment rules.

#'

#' @aliases IncrementsMin

#' @export

#'

.IncrementsMin <- setClass(

  Class = "IncrementsMin",

  slots = c(increments_list = "list"),

  prototype = prototype(

    increments_list = list(

      IncrementsRelativeDLT(intervals = c(0L, 1L), increments = c(2, 1)),

      IncrementsRelative(intervals = c(0, 2), increments = c(2, 1))

    )

  ),

  contains = "Increments",

  validity = v_increments_min

)

## constructor ----

#' @rdname IncrementsMin-class

#'

#' @param increments_list (`list`)\cr see slot definition.

#'

#' @example examples/Rules-class-IncrementsMin.R

#' @export

#'

IncrementsMin <- function(increments_list) {

}

## default constructor ----

#' @rdname IncrementsMin-class

#' @note Typically, end users will not use the `.DefaultIncrementsMin()` function.

#' @export

.DefaultIncrementsMin <- function() {

    )

  )

}

# Stopping ----

## class ----

#' `Stopping`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' [`Stopping`] is a class for stopping rules.

#'

#' @slot report_label (`string`)\cr a label for the stopping report. The meaning

#'   of this parameter is twofold. If it is equal to `NA_character_` (default),

#'   the `report_label` will not be used in the report at all. Otherwise, if it

#'   is specified as an empty character (i.e. `character(0)`) in a user constructor,

#'   then a default, class-specific label will be created for this slot.

#'   Finally, for the remaining cases, a user can provide a custom label.

#'

#' @seealso [`StoppingList`], [`StoppingCohortsNearDose`], [`StoppingPatientsNearDose`],

#'   [`StoppingMinCohorts`], [`StoppingMinPatients`], [`StoppingTargetProb`],

#'   [`StoppingMTDdistribution`], [`StoppingTargetBiomarker`], [`StoppingHighestDose`]

#'   [`StoppingMTDCV`], [`StoppingLowestDoseHSRBeta`], [`StoppingSpecificDose`].

#'

#' @aliases Stopping

#' @export

#'

setClass(

  Class = "Stopping",

  contains = "CrmPackClass",

  slots = c(report_label = "character"),

  prototype = prototype(report_label = character(0))

)

# StoppingMissingDose ----

## class ----

#' `StoppingMissingDose`

#'

#' @description `r lifecycle::badge("experimental")`

#'

#' [`StoppingMissingDose`] is the class for stopping based on NA returned by

#'  next best dose.

#'

#' @aliases StoppingMissingDose

#' @export

#'

.StoppingMissingDose <- setClass(

  Class = "StoppingMissingDose",

  contains = "Stopping"

)

## constructor ----

#' @rdname StoppingMissingDose-class

#' @param report_label (`string` or `NA`)\cr see slot definition.

#' @example examples/Rules-class-StoppingMissingDose.R

#' @export

#'

StoppingMissingDose <- function(

    report_label = NA_character_) {

  )

}

## default constructor ----

#' @rdname StoppingMissingDose-class

#' @note Typically, end users will not use the `.DefaultStoppingMissingDose()` function.

#' @export

#'

.DefaultStoppingMissingDose <- function() {

}

# StoppingCohortsNearDose ----

## class ----

#' `StoppingCohortsNearDose`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' [`StoppingCohortsNearDose`] is the class for stopping based on number of

#' cohorts near to next best dose.

#'

#'

#' @slot nCohorts (`number`)\cr number of required cohorts.

#' @slot percentage (`number`)\cr percentage (between and including 0 and 100)

#'   within the next best dose the cohorts must lie.

#'

#' @aliases StoppingCohortsNearDose

#' @export

#'

.StoppingCohortsNearDose <- setClass(

  Class = "StoppingCohortsNearDose",

  slots = c(

    nCohorts = "integer",

    percentage = "numeric"

  ),

  prototype = prototype(

    nCohorts = 2L,

    percentage = 50

  ),

  contains = "Stopping",

  validity = v_stopping_cohorts_near_dose

)

## constructor ----

#' @rdname StoppingCohortsNearDose-class

#'

#' @param nCohorts (`number`)\cr see slot definition.

#' @param percentage (`number`)\cr see slot definition.

#' @param report_label (`string` or `NA`)\cr see slot definition.

#'

#' @example examples/Rules-class-StoppingCohortsNearDose.R

#' @export

#'

StoppingCohortsNearDose <- function(nCohorts = 2L,

                                    percentage = 50,

                                    report_label = NA_character_) {

  )

  )

}

## default constructor ----

#' @rdname StoppingCohortsNearDose-class

#' @note Typically, end users will not use the `.DefaultStoppingCohortsNearDose()` function.

#' @export

.DefaultStoppingCohortsNearDose <- function() { # nolint

  )

}

# StoppingPatientsNearDose ----

## class ----

#' `StoppingPatientsNearDose`

#'

#' @description `r lifecycle::badge("stable")`

#'

#' [`StoppingPatientsNearDose`] is the class for stopping based on number of

#' patients near to next best dose.

#'

#' @slot nPatients (`number`)\cr number of required patients.

#' @slot percentage (`number`)\cr percentage (between and including 0 and 100)

#'   within the next best dose the patients must lie.

#'